DocC: Is it possible to truly compile the tutorial's code and get compiler errors/warnings

The idea is to make it easer to update documentation when API changes or when code is not correct.

Is it possible to make the code file declared like this:

@Code(name: "AppDelegate.swift", file: AppDelegate.swift)

And the content of the AppDelegate.swift file is:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        compiler error should be raised here
        
        return true
    }
}

After doing "Product > Build Documentation" the output gives the following documentation and there is not warning or errors during the build:

Thank you for your answers.

Answered by Developer Tools Engineer in 775170022

DocC doesn't build the tutorial code files for a few reasons:

  • The code files could be in any language, not just Swift.
  • The code files may represent multiple stages of the same file which wouldn't be buildable together. For example, if two code files show a class and add a method to that class there would be two colliding class definitions if both code files were built together.
  • The code files may require additional resources or dependencies—that aren't part of the tutorial project—to build.

If you are writing a tutorial about a project that is buildable on its own and wanted to verify that that project builds without errors; you would need to configure your project with one target that builds the code and one target that builds the tutorial and have them share code files. However, if your tutorials have multiple stages of the same file it's possible that you can't build all tutorial code files in a single target. In this case you may need to define multiple targets that represent different stages of the project.

Accepted Answer

DocC doesn't build the tutorial code files for a few reasons:

  • The code files could be in any language, not just Swift.
  • The code files may represent multiple stages of the same file which wouldn't be buildable together. For example, if two code files show a class and add a method to that class there would be two colliding class definitions if both code files were built together.
  • The code files may require additional resources or dependencies—that aren't part of the tutorial project—to build.

If you are writing a tutorial about a project that is buildable on its own and wanted to verify that that project builds without errors; you would need to configure your project with one target that builds the code and one target that builds the tutorial and have them share code files. However, if your tutorials have multiple stages of the same file it's possible that you can't build all tutorial code files in a single target. In this case you may need to define multiple targets that represent different stages of the project.

DocC: Is it possible to truly compile the tutorial's code and get compiler errors/warnings
 
 
Q